<ui:composition template="/WEB-INF/templates/showcase.xhtml"
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:o="http://omnifaces.org/ui"
>
	<ui:define name="description">
		<p>
			The required attribute of a <code>UISelectBoolean</code> component like <code>&lt;h:selectBooleanCheckbox&gt;</code>
			is a bit non-intuitive. If you want to require the user to tick the desired checkbox, you would expect that
			setting <code>required="true"</code> is sufficient.
		</p>
		<p>
			But it is not. As for every other <code>UIInput</code> component the default <code>required="true"</code> 
			validator would only check if the value is actually filled and is been sent to the server side, i.e. the
			value is not null nor empty. In case of a <code>&lt;h:selectBooleanCheckbox&gt;</code>, which accepts
			<code>Boolean</code> or <code>boolean</code> properties only, JSF EL will coerce the unchecked value to
			<code>Boolean.FALSE</code> during apply request values phase, right before validations phase. This value is
			not null nor empty! Thus, the required attribute of the <code>&lt;h:selectBooleanCheckbox&gt;</code> is
			fairly pointless. It would always pass the validation and thus never display the desired required message
			in case of an unticked checkbox.
		</p>
		<p>
			The <code>omnifaces.RequiredCheckboxValidator</code> is intented to solve this peculiar problem.
		</p>
	</ui:define>

	<ui:define name="demo">
		<h3>Form without <code>RequiredCheckboxValidator</code></h3>
		<h:form>
			<h:panelGrid columns="3">
				<h:outputLabel for="agree" value="Do you agree?" />
				<h:selectBooleanCheckbox id="agree" required="true" requiredMessage="You must agree!" />
				<h:message for="agree" />

				<h:panelGroup />
				<h:commandButton value="Submit">
					<f:ajax execute="@form" render="@form" />
				</h:commandButton>
				<h:panelGroup>
					<h:outputText value="OK!" rendered="#{facesContext.postback and not facesContext.validationFailed}" />
				</h:panelGroup>
			</h:panelGrid>
		</h:form>

		<hr />

		<h3>Form with <code>RequiredCheckboxValidator</code></h3>
		<h:form>
			<h:panelGrid columns="3">
				<h:outputLabel for="agree" value="Do you agree?" />
				<h:selectBooleanCheckbox id="agree" requiredMessage="You must agree!">
					<f:validator validatorId="omnifaces.RequiredCheckboxValidator" />
				</h:selectBooleanCheckbox>
				<h:message for="agree" />

				<h:panelGroup />
				<h:commandButton value="Submit">
					<f:ajax execute="@form" render="@form" />
				</h:commandButton>
				<h:panelGroup>
					<h:outputText value="OK!" rendered="#{facesContext.postback and not facesContext.validationFailed}" />
				</h:panelGroup>
			</h:panelGrid>
		</h:form>
	</ui:define>
</ui:composition>